Skip to main content

Self Description

In REST, a self-descriptive message is a request or response that contains all the information needed to understand and process it, without relying on out-of-band documentation.

This is one of Roy Fielding’s core REST constraints.

A client should be able to understand what the message means and how to process it just by reading the message itself.

What Makes a Message Self-Descriptive​

A REST message is self-descriptive when it includes:

ElementPurpose
HTTP methodIntent (GET, POST, PUT, DELETE)
Media typeHow to interpret payload
HeadersMetadata & processing rules
Status codesOutcome semantics
BodyResource representation
Links / relationsNavigation & actions

Non-Self-Descriptive vs Self-Descriptive​

Non-Self-Descriptive​

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": 1,
  "data": "ok"
}
  • Meaning of status: 1 unclear
  • No semantic hints
  • Requires external documentation

Self-Descriptive​

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-cache

{
  "id": 42,
  "name": "John Doe",
  "email": "john@example.com"
}
  • HTTP status conveys success
  • Media type tells how to parse content
  • Field names describe meaning

Media Types & Self-Descriptiveness​

Custom or structured media types increase clarity:

Content-Type: application/vnd.example.user+json

This explicitly states: Domain (example), Resource (user), Format (json)

This improves: Semantic understanding, Discoverability, Evolution/versioning